---
title: Settings
description: Meltano supports a number of settings that allow you to fine tune its behavior, which are documented here.
layout: doc
sidebar_position: 2
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Meltano supports a number of settings that allow you to fine tune its behavior, which are documented here.
To quickly find the setting you're looking for, use the Table of Contents in the sidebar.

As described in the [Configuration guide](/guide/configuration#configuration-layers), Meltano will determine the values of these settings by first looking in [**the environment**](/guide/configuration#configuring-settings), then in your project's [**`.env` file**](/concepts/project#env), and finally in your [**`meltano.yml` project file**](/concepts/project#meltano-yml-project-file), falling back to a default value if nothing was found.

You can use [`meltano config meltano list`](/reference/command-line-interface#config) to list all available settings with their names, [environment variables](/guide/configuration#configuring-settings), and current values.

Configuration that is _not_ environment-specific or sensitive should be stored in your [`meltano.yml` project file](/concepts/project#meltano-yml-project-file) and checked into version
control. Sensitive values like passwords and tokens are most appropriately stored in the environment or your project's [`.env` file](/concepts/project#env).

[`meltano config meltano set <setting> <value>`](/reference/command-line-interface#config), which is used in the examples below, will automatically store configuration in `meltano.yml` or `.env` as appropriate.

You can customize how `meltano.yml` is formatted (indentation, spacing, etc.) using Meltano's [user YAML configuration](/guide/user-yaml-config).

If supported by the plugin type, its configuration can be tested using [`meltano config <plugin> test`](../reference/command-line-interface#config).

## Plugin settings

For plugin settings, refer to the specific plugin's documentation
([extractors](https://hub.meltano.com/extractors/), [loaders](https://hub.meltano.com/loaders/)),
or use [`meltano config <plugin> list`](/reference/command-line-interface#config)
to list all available settings with their names, environment variables, and current values.

### <a name="plugin-python"></a>`python`

The python version to use for this plugin, specified as a path, or as the name of an executable to find within a directory in `$PATH`. You can set it at the time you add a plugin using [`meltano add --python <python>`](/reference/command-line-interface#add).

If not specified, [the top-level `python` setting will be used](#project-python), or if it is not set, the python executable that was used to run Meltano will be used (within a separate virtual environment).

This setting only applies when creating new virtual environments. If you've already created a virtual environment and you'd like to use a new Python version for it, you'll need to delete it from within `.meltano/`, then run `meltano install` for that plugin again.

This setting only applies to base plugins, which have their own virtual environment. Inherited plugins necessarily use the same virtual environment (and thus, the Python version) as their base plugin.

Example:

```yaml
plugins:
  extractors:
  - name: tap-gitlab
    variant: meltanolabs
    python: /path/to/python3.10
  loaders:
  - name: target-postgres
    variant: meltanolabs
    python: python3.10 # if it's in your $PATH
```

## Your Meltano project

These are settings specific to [your Meltano project](/concepts/project).

### <a name="default-environment"></a>`default_environment`

- [Environment variable](../guide/configuration#configuring-settings): `MELTANO_DEFAULT_ENVIRONMENT`
- Default: `dev`

The default environment to use when no environment is explicitly specified.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set default_environment prod
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DEFAULT_ENVIRONMENT=prod
```

  </TabItem>
</Tabs>

### <a name="project-python"></a>`python`

- [Environment variable](../guide/configuration#configuring-settings): `MELTANO_PYTHON`

The python version to use for plugins, specified as a path, or as the name of an executable to find within a directory in `$PATH`.

If not specified, the python executable that was used to run Meltano will be used (within a separate virtual environment).

[This can be overridden on a per-plugin basis by setting the `python` property for the plugin.](#plugin-python)

This setting only applies when creating new virtual environments. If you've already created a virtual environment and you'd like to use a new Python version for it, you'll need to delete it from within `.meltano/`, then run `meltano install` for that plugin again.

This setting only applies to base plugins, which have their own virtual environment. Inherited plugins necessarily use the same virtual environment (and thus, the Python version) as their base plugin.

Example:

```yaml
python: /path/to/python3.10 # or just python3.10 if it's in your $PATH
plugins:
  extractors: ...
  loaders: ...
```

### <a name="send_anonymous_usage_stats"></a>`send_anonymous_usage_stats`

- [Environment variable](../guide/configuration#configuring-settings): `MELTANO_SEND_ANONYMOUS_USAGE_STATS`
- [`meltano init`](../reference/command-line-interface#init) CLI option: `--no-usage-stats` (implies value `false`)
- Default: `true`

Meltano is open source software thats free for anyone to use. The best thing a user could do to give back to the community, aside from contributing code or reporting issues, is contribute anonymous usage stats to allow the maintainers to understand how features are being utilized ultimately helping the community build a better product.

By default, Meltano shares anonymous usage data with the Meltano team using Snowplow. We use this data to learn about the size of our user base and the specific Meltano features they are using, which helps us determine the highest impact changes we can make in each release to make Meltano even more useful for you and others like you.

We also provide some of this data back to the community via [MeltanoHub](https://hub.meltano.com/) to help users understand the overall usage of plugins within Meltano.

If enabled, Meltano will use the value of the [`project_id` setting](#project-id) to uniquely identify your project. If the project ID is a UUID, then it will be sent unchanged. Otherwise, it will be [hashed](#q-what-is-a-one-way-hash-and-how-is-it-helpful), and its hash will be used to derive a UUID which will be used to uniquely identify your project.

This project ID is also sent along when Meltano requests available plugins from the URLs identified by the [`hub_url`](#hub-url).

If you'd like to send the tracking data to a different Snowplow account than the one run by the Meltano team,
the collector endpoints can be configured using the [`snowplow.collector_endpoints` setting](#snowplowcollector_endpoints).

See more about our [anonymization standards](#anonymization-standards) and [anonymous usage stats Q&A](#anonymous-usage-stats-qa) below for more details.
Also refer to the Meltano data team handbook page for our ["Philosophy of Telemetry"](https://handbook.meltano.com/data-team/telemetry#philosophy-of-telemetry).

With all that said, if you'd still prefer to use Meltano _without_ sending the maintainers this kind of data, you're able to disable tracking entirely using one of these methods:

- When creating a new project, pass `--no-usage-stats` to [`meltano init`](/reference/command-line-interface#init)
- In an existing project, set the `send_anonymous_usage_stats` setting to `false`
- To disable tracking in all projects in one go, set the `MELTANO_SEND_ANONYMOUS_USAGE_STATS` environment variable to `false`

#### How to use

<Tabs className="meltano-tabs" groupId="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set send_anonymous_usage_stats false
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_SEND_ANONYMOUS_USAGE_STATS=false
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="meltano init" label="meltano init" default>

```bash
meltano init --no-usage-stats demo-project
```

</TabItem>
</Tabs>

#### Anonymization Standards

Unless otherwise approved, any user-entered data is anonymized client-side before being submitted to Meltano. This section describes which data is sent in clear text and which data is obfuscated via one-way hashing.

We capture these in clear text:

- plugin names
- plugin variant names
- command names
- execution context, such as:
  - OS version
  - Python version
  - project ID

We anonymize these with one-way hashing before reporting:

- CLI args
- plugin config

These items will never be collected or reported back to meltano:

- your settings values
- your secrets or credentials
- the contents of your `meltano.yml` file

#### Anonymous Usage Stats Q&A

##### Q: What is a one way hash and how is it helpful?

**A:**

One-way hashing is a way of obfuscating sensitive data such that:

1. The same input value always produces the same output value (aka "hash").
2. The results are mathematically and statistically _extremely difficult_ (read: near impossible) to reverse engineer back to the source value.
3. Hash results are extremely helpful in safely and anonymously detecting changes to a file or configuration. Without passing the entire configuration, and without providing a hacker any means of decoding/decrypting the data back to its source, we can see that a file (such as `meltano.yml`) has not changed since its last hash was generated.

##### Q: Why does Meltano use hashing?

**A:**

Meltano hashes any fields at all which could be used by a hacker to compromise a project or user. We will never know what freeform text arguments you passed in via the command line, we won't have any data at all which could be used to compromise your environment, and whatever data we collect, we'll never sell, share, or trade your data with any third parties.

##### Should I enable or disable anonymous reporting?

**A:**

We hope you will choose to enable reporting, because this really does help us - and it helps the Meltano community in a very real way.

If you still have any concerns about keeping anonymous reporting enabled, we hope you'll share those concerns with us. You can do so by emailing `hello@meltano.com` or by logging an issue in our [Meltano Issue Tracker](https://github.com/meltano/meltano/issues).

### <a name="disable-tracking"></a>`disable_tracking`

- [Environment variable](../guide/configuration#configuring-settings): `MELTANO_DISABLE_TRACKING`
- Default: `None`

Alternative way to disable tracking. When set to any truthy value, disables all tracking functionality.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set disable_tracking true
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DISABLE_TRACKING=true
```

  </TabItem>
</Tabs>

### <a name="project-id"></a>`project_id`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_PROJECT_ID`
- Default: None

Used by Meltano to uniquely identify your project if the [`send_anonymous_usage_stats` setting](#send-anonymous-usage-stats) is enabled.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set project_id '<unique identifier>'
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_PROJECT_ID='<unique identifier>'
```

  </TabItem>
</Tabs>

### <a name="database-uri"></a>`database_uri`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_DATABASE_URI`
- `meltano *` CLI option: `--database-uri`
- Default: `sqlite:///$MELTANO_SYS_DIR_ROOT/meltano.db`

Meltano stores various types of metadata in a project-specific [system database](/concepts/project#system-database),
that takes the shape of a SQLite database stored inside the [`.meltano` directory](/concepts/project#meltano-directory) at `.meltano/meltano.db` by default.

You can choose to use a different system database backend or configuration using the `--database-uri`
option of [`meltano` subcommands](/reference/command-line-interface), or the `MELTANO_DATABASE_URI` environment variable.

The database URI should be a valid [SQLAlchemy database URL](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls), and can be used to connect to [a variety of database backends](/concepts/project/#support-for-other-database-types).

:::caution
Because internal database migrations make of use of the <code>ALTER TABLE table RENAME COLUMN oldname TO newname</code> syntax starting with Meltano <code>v2.2.0</code>, the minimum required SQLite version is now <a href="https://sqlite.org/releaselog/3_25_1.html"><code>3.25.1</code></a>.

Some systems may come with an older version by default. You can run <code>sqlite3 --version</code> to check your version.
:::

#### How to use

###### PostgreSQL
<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set database_uri postgresql+psycopg://<username>:<password>@<host>:<port>/<database>
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DATABASE_URI=postgresql+psycopg://<username>:<password>@<host>:<port>/<database>
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="meltano run" label="meltano run" default>

```bash
meltano run --database-uri=postgresql+psycopg://<username>:<password>@<host>:<port>/<database> ...
```

  </TabItem>
</Tabs>


###### SQL Server (MSSQL)
<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set database_uri mssql+pymssql://<username>:<password>@<host>:<port>/<database>
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DATABASE_URI=mssql+pymssql://<username>:<password>@<host>:<port>/<database>
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="meltano run" label="meltano run" default>

```bash
meltano run --database-uri=mssql+pymssql://<username>:<password>@<host>:<port>/<database> ...
```

  </TabItem>
</Tabs>

:::info
Using databases other than SQLite requires installing Meltano with [extra components](/guide/advanced-topics#installing-optional-components).
:::

#### PostgreSQL Database Privileges and Requirements

When using PostgreSQL as your system database, the database user must have sufficient privileges to create and manage the tables that Meltano uses for storing metadata, job execution history, and incremental state.

##### Minimum PostgreSQL Version
- **PostgreSQL 13 or higher** is recommended

##### Installation with PostgreSQL Support
See the guide for how to install [optional components](/guide/advanced-topics/#installing-optional-components).

##### Required Database Privileges

The PostgreSQL user specified in your `database_uri` must have the following privileges:

**Database-level privileges:**
- `CONNECT` - To connect to the database
- `CREATE` - To create schemas during initialization
- `TEMPORARY` - To create temporary tables during operations

**Schema-level privileges** (on the target schema, typically `public`):
- `CREATE` - To create tables and other database objects
- `USAGE` - To access and use the schema

**Object-level privileges:**
- `SELECT`, `INSERT`, `UPDATE`, `DELETE` on all Meltano tables
- `USAGE`, `SELECT` on all sequences used by Meltano tables

##### Setting Up Database Privileges

To grant the necessary privileges to your Meltano database user:

```sql
-- Connect as a superuser or database owner
-- Replace 'meltano_user' with your actual username
-- Replace 'your_database' with your actual database name

-- Grant database-level privileges
GRANT CONNECT, CREATE, TEMPORARY ON DATABASE your_database TO meltano_user;

-- Grant schema-level privileges (assuming 'public' schema)
GRANT CREATE, USAGE ON SCHEMA public TO meltano_user;

-- Grant privileges on existing tables and sequences
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO meltano_user;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO meltano_user;

-- Set default privileges for future objects created by other users
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO meltano_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO meltano_user;
```

##### Tables Created by Meltano

Meltano will automatically create several tables in your PostgreSQL database:
- `runs` - Stores job execution history and metadata
- `state` - Stores incremental state for pipeline runs
- `plugin_settings` - Stores plugin configuration
- `alembic_version` - Tracks database schema version for migrations

##### Database Migration Support

Meltano uses [Alembic](https://alembic.sqlalchemy.org/) to manage database schema changes. The system will automatically run migrations when needed, which requires the user to have `ALTER TABLE` privileges on existing tables.

##### Security Considerations

- Use a dedicated database user for Meltano operations, granting it only the minimum privileges required to function. This follows the principle of least privilege and helps reduce security risks.
- Consider using environment variables or a `.env` file to store database credentials securely
- Enable SSL connections by adding appropriate parameters to your `database_uri`
- Regularly review and audit database access logs

#### Targeting a PostgreSQL Schema

When using PostgreSQL as your [system database](/concepts/project#system-database), you can choose the target schema within that database by adding
`?options=-csearch_path%3D<schema>` directly to the end of your `database_uri` and `MELTANO_DATABASE_URI`.

You are also able to add multiple schemas, which PostgreSQL will work through from left to right until it finds a valid schema to target, by using `?options=-csearch_path%3D<schema>,<schema_two>`

If you dont target a schema then by default PostgreSQL will try to use the `public` schema.

```bash
postgresql+psycopg://<username>:<password>@<host>:<port>/<database>?options=-csearch_path%3D<schema>
```

### `database_max_retries`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_DATABASE_MAX_RETRIES`
- Default: `3`

This sets the maximum number of reconnection attempts in case the initial connection to the database fails because it isn't available when Meltano starts up.

Note: This affects the initial connection attempt only after which the connection is cached.
Subsequent disconnections are handled by SQLALchemy

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set database_max_retries 3
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DATABASE_MAX_RETRIES=3
```

  </TabItem>
</Tabs>

### `database_retry_timeout`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_DATABASE_RETRY_TIMEOUT`
- Default: `5` (seconds)

This controls the retry interval (in seconds) in case the initial connection to the database fails because it isn't available when Meltano starts up.

Note: This affects the initial connection attempt only after which the connection is cached.
Subsequent disconnections are handled by SQLALchemy

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set database_retry_timeout 5
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_DATABASE_RETRY_TIMEOUT=5
```

  </TabItem>
</Tabs>

### <a name="project-readonly"></a>`project_readonly`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_PROJECT_READONLY`
- Default: `false`

Enable this setting to indicate that your Meltano project is deployed as read-only, and to block all modifications to project files through the [CLI](/reference/command-line-interface) in this environment.

Specifically, this prevents [adding plugins](/reference/command-line-interface#add) or [pipeline schedules](/reference/command-line-interface#schedule) to your [`meltano.yml` project file](/concepts/project#meltano-yml-project-file), as well as [modifying plugin configuration](/reference/command-line-interface#config) stored in [`meltano.yml`](/concepts/project#meltano-yml-project-file) or [`.env`](/concepts/project#env).

Note that [`meltano config <plugin> set`](/reference/command-line-interface#config) can still be used to store configuration in the [system database](/concepts/project#system-database), but that settings that are already [set in the environment](/guide/configuration#configuring-settings) or `meltano.yml` take precedence and cannot be overridden.

#### How to use


<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set project_readonly true
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_PROJECT_READONLY=true
```

  </TabItem>
</Tabs>

### <a name="hub-api-root"></a>`hub_api_root`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_HUB_API_ROOT`
- Default: None

This sets the value of the root url for the hub api.

If provided, this setting overrides the [`hub_url`](#hub-url).

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set hub_api_root "https://mysite.com/my-plugins"
meltano config meltano set hub_api_root false
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_HUB_API_ROOT="https://mysite.com/my-plugins"
export MELTANO_HUB_API_ROOT=false
```

  </TabItem>
</Tabs>

### <a name="hub-url"></a>`hub_url`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_HUB_URL`
- Default: `https://hub.meltano.com`

Where Meltano can find the Hub that lists all [discoverable plugins](/concepts/plugins#discoverable-plugins).

The Hub is primarily used by [`meltano add`](/reference/command-line-interface#add) and [`meltano lock`](/reference/command-line-interface#lock). It is also used in cases where the full plugin definition is needed but no lock artifact is found.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set hub_url http://localhost:4000
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_HUB_URL=http://localhost:4000
```

  </TabItem>
</Tabs>

### <a name="hub-url-auth"></a>`hub_url_auth`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_HUB_URL_AUTH`
- Default: None

The value of the `Authorization` header sent when making a request to [`hub_url`](#hub-url).

No `Authorization` header is applied under the following conditions:

- `hub_url_auth` is not set
- `hub_url_auth` is set to `false`, `null` or an empty string

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set hub_url_auth "Bearer $ACCESS_TOKEN"
meltano config meltano set hub_url_auth false
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_HUB_URL_AUTH="Bearer $ACCESS_TOKEN"
export MELTANO_HUB_URL_AUTH=false
```

  </TabItem>
</Tabs>

### <a name="auto-install"></a>`auto_install`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_AUTO_INSTALL`
- Default: `true`

Whether to automatically install any required plugins on command invocation. A plugin will be auto-installed when its virtual environment does not already exist or `pip_url` is changed.

Auto-install pertains to the following commands:
- [`meltano add`](/reference/command-line-interface#add)
- [`meltano config <plugin> test`](/reference/command-line-interface#config)
- [`meltano select --list`](/reference/command-line-interface#select)
- [`meltano test`](/reference/command-line-interface#test)
- [`meltano invoke`](/reference/command-line-interface#invoke)
- [`meltano el`](/reference/command-line-interface#el) / [`meltano elt`](/reference/command-line-interface#elt)
- [`meltano run`](/reference/command-line-interface#run)

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set auto_install true
meltano config meltano set auto_install false
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_AUTO_INSTALL=true
export MELTANO_AUTO_INSTALL=false
```

  </TabItem>
</Tabs>

## `meltano` CLI

These settings can be used to modify the behavior of the [`meltano` CLI](/reference/command-line-interface).

### <a name="cli-log-level"></a>`cli.log_level`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_CLI_LOG_LEVEL`.
- `meltano` CLI option: `--log-level`
- Options: `debug`, `info`, `warning`, `error`, `critical`, `disabled`
- Default: `info`

The granularity of CLI logging. Ignored if a local logging config is found.

The `disabled` option completely suppresses all logging output, which is useful for scripts that need to parse Meltano output or for running commands in completely silent mode.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set cli log_level debug
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_CLI_LOG_LEVEL=debug
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="command" label="command" default>

```bash
meltano --log-level=debug ...
```

  </TabItem>
</Tabs>

### `cli.log_format`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_CLI_LOG_FORMAT`.
- `meltano` CLI option: `--log-format`
- Options: `colored`, `uncolored`, `json`, `key_value`, `plain`
- Default: `colored`

A shortcut for setting the format of the log output. Ignored if a local logging config is found.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set cli log_format json
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_CLI_LOG_FORMAT=json
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="command" label="command" default>

```bash
meltano --log-format=json ...
```

  </TabItem>
</Tabs>

### `cli.log_config`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_CLI_LOG_CONFIG`.
- `meltano` CLI option: `--log-config`
- Default: `logging.yaml`

The path of a valid yaml formatted [python logging dict config file](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema) to use to configure logging _if present_. Supports both `.yaml` and `.yml` file extensions.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set cli log_config /path/to/logging.yaml
# or
meltano config meltano set cli log_config /path/to/logging.yml
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_CLI_LOG_CONFIG=/path/to/logging.yaml
# or
export MELTANO_CLI_LOG_CONFIG=/path/to/logging.yml
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="command" label="command" default>

```bash
meltano --log-config=/path/to/logging.yaml ...
# or
meltano --log-config=/path/to/logging.yml ...
```

  </TabItem>
</Tabs>

A sample logging config:

```yaml
version: 1
disable_existing_loggers: false

formatters:
  default:
    format: "[%(asctime)s] [%(process)d|%(threadName)10s|%(name)s] [%(levelname)s] %(message)s"
  structured_plain:
    (): meltano.core.logging.console_log_formatter
    colors: False
  structured_colored:
    (): meltano.core.logging.console_log_formatter
    colors: True
  key_value:
    (): meltano.core.logging.key_value_formatter
    sort_keys: False
  json:
    (): meltano.core.logging.json_formatter

handlers:
  console:
    class: logging.StreamHandler
    level: DEBUG
    formatter: structured_colored
    stream: "ext://sys.stderr"
  file:
    class: logging.FileHandler
    level: INFO
    filename: /var/log/meltano.log
    formatter: json

root:
  level: DEBUG
  propagate: yes
  handlers: [console, file]
```

### <a name="cli-cwd"></a>`cli.cwd`

- `meltano` CLI option: `--cwd`
- Default: `Current directory`

With `--cwd` option you can run Meltano as if had been started in a specified directory.

#### How to use

Specify path to a directory which contains a valid [`meltano.yml` project file](/concepts/project#meltano-yml-project-file).

```bash
meltano --cwd '/path/containing/meltano_yml'
```

## `meltano elt`

These settings can be used to modify the behavior of [`meltano el`](/reference/command-line-interface#el) and [`meltano elt`](/reference/command-line-interface#elt).

### `elt.buffer_size`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_ELT_BUFFER_SIZE`
- Default: `104857600` (100MiB in bytes)

Size (in bytes) of the buffer between extractor and loader (Singer tap and target) that stores
[messages](https://hub.meltano.com/singer/spec#messages)
output by the extractor while they are waiting to be processed by the loader.

When an extractor generates messages (records) faster than the loader can process them, the buffer may fill up completely,
at which point the extractor will be blocked until the loader has worked through enough messages to make half
of the buffer size available again for new extractor output.

The length of a single line of extractor output is limited to half the buffer size.
With a default buffer size of 100MiB, the maximum message size would therefore be 50MiB.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set elt.buffer_size 52428800 # 50MiB in bytes
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_ELT_BUFFER_SIZE=52428800
```

  </TabItem>
</Tabs>

## State Backends

### <a name="state-backend-uri"></a>`state_backend.uri`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_URI`
- Default: `systemdb`

URI for the [state backend](/concepts/state_backends) where you'd like Meltano to store state.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.uri "s3://your_bucket/meltano/state"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_URI="s3://your_bucket/meltano/state"
```

  </TabItem>
</Tabs>

### <a name="state-backend-uri"></a>`state_backend.lock_timeout_seconds`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_LOCK_TIMEOUT_SECONDS`
- Default: `10`

Number of seconds that a [lock for a state ID](/concepts/state_backends#locking) should be considered valid in a state backend

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.lock_timeout_seconds 720
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_LOCK_TIMEOUT_SECONDS=720
```

  </TabItem>
</Tabs>

### <a name="state-backend-uri"></a>`state_backend.lock_retry_seconds`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_LOCK_RETRY_SECONDS`
- Default: `1`

Number of seconds that a Meltano should wait if trying to access or modify state for a state ID that is [locked](/concepts/state_backends#locking)

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.lock_retry_seconds 720
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_LOCK_RETRY_SECONDS=720
```

  </TabItem>
</Tabs>

### Azure-Specific Settings

---

### <a name="state-backend-uri"></a>`state_backend.azure.storage_account_url`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_AZURE_STORAGE_ACCOUNT_URL`
- Default: None

One can [Sign-in to Azure](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-python?tabs=managed-identity%2Croles-azure-portal%2Csign-in-azure-cli#sign-in-and-connect-your-app-code-to-azure-using-defaultazurecredential) using the Azure CLI.

The `storage_account_url` will be used to fetch the default Azure credentials in the host system.

:::info
At least one of `state_backend.azure.storage_account_url` and `state_backend.azure.connection_string` has to be set in order to use Azure Blob Storage as a state backend. If `state_backend.azure.storage_account_url` is not set, Meltano will to try to use `state_backend.azure.connection_string`.
:::

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.azure.storage_account_url "https://<myStorageAccountName>.blob.core.windows.net"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_AZURE_STORAGE_ACCOUNT_URL="https://<myStorageAccountName>.blob.core.windows.net"
```

  </TabItem>
</Tabs>

### <a name="state-backend-uri"></a>`state_backend.azure.connection_string`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_AZURE_CONNECTION_STRING`
- Default: None

The [Azure connection string](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string) to use when authenticating to Azure.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.azure.connection_string "DefaultEndpointsProtocol=https;AccountName=myAccountName;AccountKey=myAccountKey"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=myAccountName;AccountKey=myAccountKey"
```

  </TabItem>
</Tabs>

### S3-Specific Settings

---

### <a name="state-backend-uri"></a>`state_backend.s3.aws_access_key_id`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_S3_AWS_ACCESS_KEY_ID`
- Default: None

The AWS access key ID to use when authenticating to S3.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.s3.aws_access_key_id "someaccesskeyid"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_S3_AWS_ACCESS_KEY_ID="someaccesskeyid"
```

  </TabItem>
</Tabs>

### <a name="state-backend-uri"></a>`state_backend.s3.aws_secret_access_key`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_S3_AWS_SECRET_ACCESS_KEY`
- Default: None

The AWS secret access key to use when authenticating to S3.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.s3.aws_secret_access_key "somesecretaccesskey"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_S3_AWS_SECRET_ACCESS_KEY="somesecretaccesskey"
```

  </TabItem>
</Tabs>

### <a name="state-backend-uri"></a>`state_backend.s3.endpoint_url`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_S3_ENDPOINT_URL`
- Default: None

The endpoint URL to use when connecting to S3. Only necessary if using S3-compatible storage _not_ hosted by AWS (e.g. [Minio](https://min.io))

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.s3.endpoint_url "https://play.min.io:9000"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_S3_ENDPOINT_URL="https://play.min.io:9000"
```

  </TabItem>
</Tabs>

### GCS-Specific Settings

---

### <a name="state_backendgcsapplication_credentials_json"></a>`state_backend.gcs.application_credentials_json`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS_JSON`
- Default: None

JSON string containing the service account credentials for Google Cloud Storage. This is the recommended approach for production deployments, especially in containerized environments.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.gcs.application_credentials_json '{
  "type": "service_account",
  "project_id": "my-project",
  "private_key_id": "...",
  "private_key": "...",
  "client_email": "...",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}'
```

Or set it from a file:

```bash
meltano config meltano set state_backend.gcs.application_credentials_json --from-file service-account-key.json
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS_JSON='{"type":"service_account","project_id":"my-project",...}'
```

  </TabItem>
</Tabs>

---

### <a name="state_backendgcsapplication_credentials_path"></a>`state_backend.gcs.application_credentials_path`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS_PATH`
- Default: None

Path to the [credential file](https://cloud.google.com/docs/authentication/application-default-credentials#GAC) to use in authenticating to Google Cloud Storage

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.gcs.application_credentials_path "path/to/creds.json"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS_PATH="path/to/creds.json"
```

  </TabItem>
</Tabs>

---

### <a name="state_backendgcsapplication_credentials"></a>`state_backend.gcs.application_credentials` (deprecated)

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS`
- Default: None

:::warning
This setting is deprecated. Use [`state_backend.gcs.application_credentials_path`](#state_backendgcsapplication_credentials_path) instead.
:::

Path to the [credential file](https://cloud.google.com/docs/authentication/application-default-credentials#GAC) to use in authenticating to Google Cloud Storage

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set state_backend.gcs.application_credentials "path/to/creds.json"
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_STATE_BACKEND_GCS_APPLICATION_CREDENTIALS="path/to/creds.json"
```

  </TabItem>
</Tabs>

## Virtual environments

### `venv.backend`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_VENV_BACKEND`
- Options: `virtualenv`, `uv`
- Default: `uv`

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set venv.backend virtualenv
meltano install --clean
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
MELTANO_VENV_BACKEND=virtualenv meltano install --clean
```

  </TabItem>
</Tabs>

:::info
  <p>
  After you switch to a different virtual environment backend, it's recommended to reinstall all plugins with `meltano install --clean`.
  </p>
:::

## Snowplow Tracking

### `snowplow.collector_endpoints`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_SNOWPLOW_COLLECTOR_ENDPOINTS`
- Default: `["https://sp.meltano.com"]`

Snowplow collector endpoints to be used if the [`send_anonymous_usage_stats` setting](#send-anonymous-usage-stats) is enabled. Events will be sent to all of these collectors.

## Feature Flags

### <a name="experimental"></a>`experimental`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_EXPERIMENTAL`
- Default: `False`

Whether to enable experimental features that are under development and may change or be removed in future versions.

#### How to use

<Tabs className="meltano-tabs" queryString="meltano-tabs">
  <TabItem className="meltano-tab-content" value="meltano config" label="meltano config" default>

```bash
meltano config meltano set experimental true
```

  </TabItem>
  <TabItem className="meltano-tab-content" value="env" label="env" default>

```bash
export MELTANO_EXPERIMENTAL=true
```

  </TabItem>
</Tabs>

### <a name="ff-strict-env-var-mode"></a>`ff.strict_env_var_mode`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_FF_STRICT_ENV_VAR_MODE`
- Default: `False`

Causes an exception to be raised if an environment variable is used within the project's Meltano configuration but that environment variable is not set.

### <a name="ff-plugin-locks-required"></a>`ff.plugin_locks_required`

- [Environment variable](/guide/configuration#configuring-settings): `MELTANO_FF_PLUGIN_LOCKS_REQUIRED`
- Default: `False`

When this flag is enabled, plugins will only use [lock files](/concepts/plugins#lock-artifacts) to determine the settings, installation source, etc with the exception of the `meltano add` operations. This means that calling `meltano run` will fail if a lock file is not present for one of the plugins.
